/**
 * Copyright (C) 2012 Foxit Corporation.
 * All Rights Reserved.
 *
 * The following code is copyrighted and contains proprietary information and trade secrets of Foxit Corporation.<br> 
 * You can only redistribute files listed below to customers of your application, under a written SDK license agreement with Foxit.<br>
 * You cannot distribute any part of the SDK to general public, even with a SDK license agreement.<br>
 * Without SDK license agreement, you cannot redistribute anything.
 * 
 * @file    fpdfaction.h
 * @brief   Header file for the PDF action module.<br>
 * @note	If you want to purchase Foxit PDF SDK license and use ANY of the following functions, please
 *			request for enabling PDF object module explicitly. 
 */

/** 
 * @addtogroup FGSPDFACTION PDF Action
 * @brief Methods in this module are included in fpdfaction.h.
 */
 
 /**@{*/
#ifndef __FGSPDFACTION__
#define __FGSPDFACTION__

#include "fpdfbase.h"

#ifdef __cplusplus
extern "C" {
#endif
/**
 * @brief Get the type of an action.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] action		Reference to a PDF action.
 *
 * @return	The type of the action. <br>
 *			Currently it can be one of the followings:
 *					<ul>
 *					<li>::kFGSPDFActionUnsupported</li>
 *					<li>::kFGSPDFActionGoto</li>
 *					<li>::kFGSPDFActionRemoteGoto</li>
 *					<li>::kFGSPDFActionURL</li>
 *					</ul>
 *			For more definitions please see macro definitions <b>::FGSPDFActionType</b>.
 *
 */
FGSPDFActionType FGSPDFActionGetType(FGSPDFDocumentRef document, FGSPDFActionRef action);

/**
 * @brief Get the detailed data of a particular action type which the action's type is <b>kFGSPDFActionGoto</b>.
 *
 * @details The following data structures are used for different action types returned by <b>::FGSPDFActionGetType</b>:
 *			<ul>
 *			<li>::FGSPDFPageDest</li>
 *			</ul>
 *			See the definitions of each structure above for more details.
 *			Please note the actual action data might use more space than the structure definition
 *			shows, in order to store things like file name or URL. So you should always call
 *			<b>FGSPDFActionGetType</b> first to get the data size then allocate enough buffer
 *			for calling this function.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] action		Reference to a PDF action.
 * @param[out] pageDest		Pointer to a page(allocated by the appication) that receives the destination data.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionGetPageDest(FGSPDFDocumentRef document, FGSPDFActionRef action, FGSPDFPageDest *pageDest);

/**
 * @brief Get the detailed data of a particular action type which the action's type is <b>::kFGSPDFActionRemoteGoto</b>.
 *
 * @details The following data structure <b>::FGSPDFDocDest</b> are used for different action types returned by <b>::FGSPDFActionGetType</b>.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] action		Reference to a PDF action.
 * @param[out] docDest		Pointer to the document(allocated by the appication) that receives the destination data.
 *
 * @return	::kFGSErrorSuccess means get the data successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionGetDocDest(FGSPDFDocumentRef document, FGSPDFActionRef action, FGSPDFDocDest *docDest);

/**
 * @brief Get the detailed data of a particular action which the action's type is <b>::kFGSPDFActionURL</b>.
 *
 * @param[in] document		Reference to a PDF document.
 * @param[in] action		Reference to a PDF action.
 *
 * @return	The URL string of action, user should release the string by calling <b>CFRelease</b>.
 *
 */
CFStringRef FGSPDFActionCopyURIFromAction(FGSPDFDocumentRef document, FGSPDFActionRef action);

/**
 * @brief Get the next action in an action chain.
 *
 * @param[in] action		Reference to a PDF action.
 *
 * @return	Reference to the next PDF action.
 *
 */
FGSPDFActionRef FGSPDFActionGetNext(FGSPDFActionRef action);
   
/**
 * @brief Creates an action.
 * 
 * @param[in] document		Reference to a PDF document that will contains the action.
 * @param[in] actiontype	The type of the action. The values are defined above.
 * 
 * @return Reference to a PDF action or NULL if an error occurs.
 */
FGSPDFActionRef FGSPDFActionCreate(FGSPDFDocumentRef document, FGSPDFActionType actionType);

/**
 * @brief Deletes an action.
 *
 * @param[in] action        Reference to an PDF action.
 *
 * @return TRUE for success, otherwise FALSE.
 */
FGSErrorRet FGSPDFActionDestroy(FGSPDFActionRef action);

/** 
 * @brief Set the annot, only for rendition action type. 
 *
 * @param[in] action        Reference to a PDF action.
 * @param[in] page          Reference to a PDF page.
 * @param[in] annot         Reference to a PDF annot. 
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetAnnot(FGSPDFActionRef action, FGSPDFPageRef page, FGSPDFAnnotRef annot);

/** 
 * @brief Get the annot, only for rendition action type. 
 *
 * @param[in] action        Reference to a PDF action.
 * @param[in] page          Reference to a PDF page.
 *
 * @return	The returned PDF annot reference. 
 *
 * @note The type of the annot belonged to the action must be <b>kFGSPDFAnnotTypeScreen</b>, if not, return <b>NULL</b>.
 */
FGSPDFAnnotRef FGSPDFActionGetAnnot(FGSPDFActionRef action, FGSPDFPageRef page);

/**
 * @brief Sets the type of action's destination.
 * 
 * @param[in] document	    Reference to a PDF document.
 * @param[in] action	 	Reference to a PDF action.
 * @param[in] dest		    Pointer to a PDF destination.
 * 
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFActionSetPageDest(FGSPDFDocumentRef document, FGSPDFActionRef action, FGSPDFPageDest *pageDest);

/**
 * @brief Set the type of action's destination.
 * 
 * @param[in] document	    Reference to a PDF document.
 * @param[in] action	 	Reference to a PDF action.
 * @param[in] dest		    Pointer to a PDF destination.
 * 
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet	FGSPDFActionSetDocDest(FGSPDFDocumentRef document, FGSPDFActionRef action, FGSPDFDocDest *docDest);

/**
 * @brief Set the URI path of Action
 * 
 * @param[in] document		Reference to a PDF document.
 * @param[in] action		Reference to a PDF action.
 * @param[in] uri     		URL address.
 * 
 * @return ::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 */
FGSErrorRet FGSPDFActionSetURI(FGSPDFDocumentRef document, FGSPDFActionRef action, CFStringRef uri);

/** 
 * @brief Set the operation type. 
 *
 * @param[in] action        Reference to a PDF action.
 * @param[in] type          The operation type.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet	FGSPDFActionSetOperationType(FGSPDFActionRef action, SInt32 type);
    
/** 
 * @brief Get the operation type. 
 *
 * @param[in] action        Reference to a PDF action.
 *
 * @return	The returned the operation type.
 *
 */
SInt32 FGSPDFActionGetOperationType(FGSPDFActionRef action);

/**
 * @brief Get the count of renditions.
 *
 * @param[in] action        Reference to a PDF action.
 *
 * @return The count of renditions.
 *
 */
SInt32 FGSPDFActionCountRenditions(FGSPDFActionRef action);

/**
 * @brief Get a rendition. 
 *
 * @param[in] action        Reference to a PDF action.
 * @param[in] iIndex        The zero-based rendition index.
 *
 * @return	The PDF rendition reference.
 *
 */
FGSPDFRenditionRef FGSPDFActionGetRendition(FGSPDFActionRef action, SInt32 index);

/** 
 * @brief Get The file specification of the actual media data.
 * 
 * @param[in] rendition		Reference to a PDF rendition.
 *
 * @return	The returned PDF filespec reference. 
 *
 */
FGSPDFFileSpecRef FGSPDFActionGetRenditionMediaClipFile(FGSPDFRenditionRef rendition);

/** 
 * @brief Get the content type (MIME type) of the media data.
 *
 * @param[in] rendition	         Reference to a PDF rendition.
 *
 * @return	The content type. 
 *
 */
CFStringRef FGSPDFActionGetRenditionMediaClipContentType(FGSPDFRenditionRef rendition);

/** 
 * @brief Get the volume that specifies the desired volume level as a percentage of recorded volume level. 
 *
 * @param[in] rendition	        Reference to a PDF rendition.
 *
 * @return	The volumn. 
 *
 */
SInt32 FGSPDFActionGetRenditionVolumn(FGSPDFRenditionRef rendition);

/** 
 * @brief Check to display a player-specific controller user interface (for example, play/pause/stop controls) when playing. 
 *
 * @param[in] rendition	         Reference to a PDF rendition.
 *
 * @return	The control bar visibility flag. 
 *
 */
Boolean	FGSPDFActionGetControlBarVisible(FGSPDFRenditionRef rendition);

/** 
 * @brief Get the intrinsic duration. 
 *
 * @param[in] rendition          Reference to a PDF rendition.
 *
 * @return	The intrinsic duration. 
 *			<ul>
 *			<li> -2: use intrinsic duration.</li>
 *			<li> -1: infinity duration.</li> 
 *			<li> >= 0: explicit duration.</li>
 *			</ul>
 *
 */
SInt32 FGSPDFActionGetRenditionDuration(FGSPDFRenditionRef rendition);

/** 
 * @brief Get the repeat count. 
 *
 * @param[in] rendition	         Reference to a PDF rendition.
 *
 * @return	The repeat count.
 *
 */
SInt32 FGSPDFActionGetRenditionRepeatCount(FGSPDFRenditionRef rendition);

/** 
 * @brief Create the rendition. 
 *
 * @param[in] document           Reference to a PDF document.
 *
 * @return	The PDF rendition reference. 
 *
 */
FGSPDFRenditionRef FGSPDFActionCreateRendition(FGSPDFDocumentRef document);

/**
 * @brief Insert a rendition.
 *
 * @param[in] document          Reference to a PDF document.
 * @param[in] action            Reference to a PDF action.
 * @param[in] rendition         Reference to a PDF rendition.
 * @param[in] iIndex            The zero-based rendition index.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionInsertRendition(FGSPDFDocumentRef document, FGSPDFActionRef action, FGSPDFRenditionRef rendition, SInt32 index);

/**
 * @brief Remove a rendition.
 *
 * @param[in] action            Reference to a PDF action.
 * @param[in] rendition         Reference to a PDF rendition.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionRemoveRendition(FGSPDFActionRef action, FGSPDFRenditionRef rendition);

/**
 * @brief Set the file specification of the actual media data.
 *
 * @param[in] rendition         Reference to a PDF rendition.
 * @param[in] pDocument         Reference to a PDF pDocument.
 * @param[in] filespec          Reference to a PDF filespec.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetRenditionMediaClipFile(FGSPDFRenditionRef rendition, FGSPDFDocumentRef document, FGSPDFFileSpecRef filespec);

/** 
 * @brief Set the content type (MIME type) of the media data.
 *
 * @param[in] rendition	        Reference to a PDF rendition.
 * @param[in] contentType  	    The String of content type. 
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet	FGSPDFActionSetRenditionMediaClipContentType(FGSPDFRenditionRef rendition, CFStringRef contentType);

/** 
 * @brief Set the volume that specifies the desired volume level as a percentage of recorded volume level. 
 *
 * @param[in] rendition	        Reference to a PDF rendition.
 * @param[in] volumn       	    The volumn. 
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetRenditionVolumn(FGSPDFRenditionRef rendition, SInt32 volumn);

/**
 * @brief Set the control bar visibility flag.
 *
 * @param[in] rendition	        Reference to a PDF rendition.
 * @param[in] visible       	The control bar visibility flag.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetRenditionControlBarVisible(FGSPDFRenditionRef rendition, Boolean visible);

/**
 * @brief Set the intrinsic duration.
 *
 * @param[in] rendition	        Reference to a PDF rendition.
 * @param[in] iDuration	    	The intrinsic duration.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetRenditionDuration(FGSPDFRenditionRef rendition, SInt32 iDuration);

/**
 * @brief Set the repeat count.
 *
 * @param[in] rendition	        Reference to a PDF rendition.
 * @param[in] repeat       	    The repeat count.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetRenditionRepeatCount(FGSPDFRenditionRef rendition, SInt32 repeat);

/**
 * @brief	Set the media permission.
 *
 * @param[in] rendition			Reference of rendition action.
 * @param[in] permission		The media permission.
 *								For more definitions please see macro definitions <b>MEDIAPERMISSION_XXX</b>.
 *
 * @return	::kFGSErrorSuccess means successfully.<br>
 *			For more definitions please see enum definitions <b>FGSErrorRet</b>.
 *
 */
FGSErrorRet FGSPDFActionSetRenditionPermission(FGSPDFRenditionRef rendition, FGSPDFMediaPermissionType permission);

/**
 * @brief	Get the media permission that indicates the circumstances under which it is acceptable to write a temporary
 *          file in order to play a media clip.
 *
 * @param[in] rendition			Reference to a PDF rendition.
 *
 * @return The permission type.
 *
 */
FGSPDFMediaPermissionType FGSPDFActionGetRenditionPermission(FGSPDFRenditionRef rendition);

#ifdef __cplusplus
};
#endif

#endif // __FGSPDFACTION__
/**@}*/
